.\" $Header$ -*-nroff-*-
.\" Purpose: ROFF man page for ncrename
.\" Usage:
.\" nroff -man ~/nco/man/ncrename.1 | less
.TH NCRENAME 1
.SH NAME
ncrename \- netCDF Renamer
.SH SYNTAX
ncrename [\-a 
.IR old_name,new_name ]
[\-a
\ .\|.\|.\ ] [\-D] 
[\-d 
.IR old_name,new_name ]
[\-d
\ .\|.\|.\ ] [\-g 
.IR old_name,new_name ] 
[\-g \ .\|.\|.\ ]
[\-\-gaa
.IR att_name=
.IR att_val ]]
[\-\-gad 
.IR att1 [,...]]
[\-H] [\-h] [\-\-hdr_pad
.IR sz_byt ] [\-\-hpss_try]
[\-l path] [\-O] [\-p path]
[\-R] [\-r] [\-\-ram_all]  [\-\-uio] [\-v 
.IR old_name,new_name ]
[\-v \ .\|.\|.\ ]
.I input-file
[
.IR output-file ]
.SH DESCRIPTION
.PP
.B ncrename
renames dimensions, variables, and attributes in a
netCDF file.  
Each object that has a name in the list of old names is renamed using
the corresponding name in the list of new names. 
All the new names must be unique. 
Every old name must exist in the input file, unless the name is preceded
by the character 
.BR . .
The validity of the old names is not checked prior to the renaming. 
Thus, if an old name is specified without the the 
.B .
prefix and is
not present in 
.IR input-file ,
.B ncrename
will abort. 
.PP
.B ncrename
is the exception to the normal rules that the user will
be interactively prompted before an existing file is changed, and that a
temporary copy of an output file is constructed during the operation.
If only 
.I input-file
is specified, then 
.B ncrename
will change
the names of the 
.I input-file
in place without prompting and without
creating a temporary copy of 
.BR input-file .
This is because the renaming operation is considered reversible if the
user makes a mistake.
The 
.I new_name
can easily be changed back to 
.I old_name
by using 
.B ncrename
one more time.
.PP
Note that renaming a dimension to the name of a dependent variable can
be used to invert the relationship between an independent coordinate
variable and a dependent variable. 
In this case, the named dependent variable must be one-dimensional and
should have no missing values. 
Such a variable will become a coordinate variable.
.PP
According to the netCDF Users Guide, renaming properties in
netCDF files does not incur the penalty of recopying the entire file
when the 
.I new_name
is shorter than the 
.IR old_name .
.SH OPTIONS
.PP
.TP
.B \-a 
.IR old_name ,
.I "new_name"
Attribute renaming. 
The old and new names of the attribute are specified by the associated
.I old_name
and 
.I new_name
values. 
Global attributes are treated no differently than variable attributes.
This option may be specified more than once.
You cannot change the attribute name for one particular variable (unless
it is uniquely named); all occurrences of the attribute of a given name
will be renamed. 
This is considered an oversight and will be addressed in a future
version of NCO.
.PP
.TP
.B \-d 
.IR old_name ,
.I "new_name"
Dimension renaming. 
The old and new names of the dimension are specified by the associated
.I old_name
and 
.I new_name
values. 
This option may be specified more than once.
.TP
.B \-g 
.IR old_name ,
.I "new_name"
Group renaming. 
The old and new names of the group are specified by the associated
.I old_name
and 
.I new_name
values. 
This option may be specified more than once.
.TP
.B \-v 
.IR old_name ,
.I "new_name"
Variable renaming. 
The old and new names of the variable are specified by the associated
.I old_name
and 
.I new_name
values. 
This option may be specified more than once.
.TP
.B \-i 
Interactive. 
.B ncrename
will prompt for confirmation before overwriting an
existing file. 
.SH EXAMPLES
.PP
Rename the variable 
.B p
to 
.B pressure
and 
.B t
to
.B temperature
in netCDF 
.BR in.nc .
In this case 
.B p
must exist in the input file (or 
.B ncrename
will
abort), but the presence of 
.B t
is optional:
.RS
ncrename \-v p,pressure \-v .t,temperature in.nc
.RE
.B ncrename
does not automatically attach dimensions to variables of
the same name.
If you want to rename a coordinate variable so that it remains a
coordinate variable, you must separately rename both the dimension and
the variable: 
.RS
ncrename \-d lon,longitude \-v lon,longitude in.nc
.RE
.PP
Create netCDF 
.B out.nc
identical to 
.B in.nc
except the attribute
.B _FillValue
is changed to 
.B missing_value
(in all variables
which possess it) and the global attribute 
.B Zaire
is changed to
.BR Congo :
.RS
ncrename \-a _FillValue,missing_value \-a Zaire,Congo in.nc out.nc 
.RE

.\" NB: Append man_end.txt here
.\" $Header$ -*-nroff-*-
.\" Purpose: Trailer file for common ending to NCO man pages
.\" Usage: 
.\" Append this file to end of NCO man pages immediately after marker
.\" that says "Append man_end.txt here"
.SH AUTHOR
.B NCO
manual pages written by Charlie Zender and originally formatted by Brian Mays.

.SH "REPORTING BUGS"
Report bugs to <http://sf.net/bugs/?group_id=3331>.

.SH COPYRIGHT
Copyright \(co 1995-present Charlie Zender
.br
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

.SH "SEE ALSO"
The full documentation for
.B NCO
is maintained as a Texinfo manual called the 
.B NCO Users Guide.
Because 
.B NCO
is mathematical in nature, the documentation includes TeX-intensive
portions not viewable on character-based displays. 
Hence the only complete and authoritative versions of the 
.B NCO Users Guide 
are the PDF (recommended), DVI, and Postscript versions at
<http://nco.sf.net/nco.pdf>, <http://nco.sf.net/nco.dvi>,
and <http://nco.sf.net/nco.ps>, respectively.
HTML and XML versions
are available at <http://nco.sf.net/nco.html> and
<http://nco.sf.net/nco.xml>, respectively.

If the
.B info
and
.B NCO
programs are properly installed at your site, the command
.IP
.B info nco
.PP
should give you access to the complete manual, except for the
TeX-intensive portions.

.BR ncap2 (1), 
.BR ncatted (1), 
.BR ncbo (1), 
.BR ncclimo (1), 
.BR nces (1), 
.BR ncecat (1), 
.BR ncflint (1), 
.BR ncz2psx (1), 
.BR ncz2psx (1), 
.BR ncks (1), 
.BR nco (1), 
.BR ncpdq (1), 
.BR ncra (1), 
.BR ncrcat (1), 
.BR ncremap (1), 
.BR ncrename (1), 
.BR ncwa (1) 

.SH HOMEPAGE
The 
.B NCO
homepage at <http://nco.sf.net> contains more information.
